Skip to content

feat(mcp): support ad hoc dashboard filters in the MCP dashboard tools - #3660

Open
knudtty wants to merge 10 commits into
aaron/adhoc-external-apifrom
aaron/adhoc-mcp
Open

knudtty wants to merge 10 commits into
aaron/adhoc-external-apifrom
aaron/adhoc-mcp

Conversation

@knudtty

@knudtty knudtty commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Stacked on #3659.

Summary

The MCP dashboard tools now create, read, and update dashboards with ADHOC filters. The previous PR left MCP hiding them. A side effect was that a clickstack_save_dashboard update that sent filters silently deleted any ad hoc filters already on the dashboard. This PR fixes that.

  • Input schemas: clickstack_save_dashboard accepts ADHOC filters, and clickstack_save_dashboard / clickstack_patch_dashboard accept adhoc entries in savedFilterValues. Validation reuses the external API schemas, so MCP and REST stay in sync; only the descriptions are MCP-specific. sourceType: "promql" is offered only while PromQL is enabled.
  • Reads: convertToExternalDashboard no longer has the temporary hideAdhoc option. hidePromql now hides PromQL ad hoc filters as well as PROMETHEUS_LABEL filters, through a shared isPromqlFilter helper.
  • Updates with PromQL off: hidden PromQL ad hoc filters are kept on update, like hidden PROMETHEUS_LABEL filters. The existing variable-name clash check also covers them.
  • Warnings: a saved adhoc entry produces a warning when its name matches no ad hoc filter, or when it uses an operator its filter's source type can't apply. The UI would silently ignore both.
  • Prompt docs: the create-dashboard prompt gets a rule 9h and two gotchas. The query guide documents the ad hoc filter shape. The PromQL dashboard section covers PromQL ad hoc filters.

How to reproduce

Starting point: yarn dev, with an MCP client connected to the local MCP server.

On main:

  1. Create a dashboard with an ad hoc filter in the UI, then call clickstack_get_dashboard. The filter is missing from filters.
  2. Call clickstack_save_dashboard with that dashboard's id and any filters array. The ad hoc filter is deleted.

On this branch:

  1. clickstack_get_dashboard returns the ad hoc filter and its adhoc saved conditions.
  2. clickstack_save_dashboard with filters: [{ "type": "ADHOC", "name": "Conditions", "sourceType": "sql", "sources": ["<trace-source-id>"] }] and savedFilterValues: [{ "type": "adhoc", "name": "Conditions", "conditions": [{ "key": "ServiceName", "operator": "IN", "value": "api" }] }] creates it. Opening the dashboard shows the condition applied.
  3. With ENABLE_PROMQL off, a PromQL ad hoc filter is absent from clickstack_get_dashboard and survives a save that leaves it out.

How to test on Vercel preview

N/A. API-only change.

Testing

  • make dev-int FILE=src/mcp/__tests__/dashboards passes. New cases cover a SQL round trip through save, get and save, a PromQL round trip, source-kind rejections, hiding and keeping PromQL ad hoc filters with PromQL off, and the warnings.
  • make dev-int FILE=src/routers/external-api/__tests__/dashboards.int.test.ts passes.

References

Save, get, and patch now handle ADHOC filters and their adhoc saved
conditions. PromQL ad hoc filters are offered only while PromQL is enabled;
otherwise reads hide them and updates keep them, as for PROMETHEUS_LABEL
filters. Saved conditions naming no ad hoc filter, or using an operator their
filter can't apply, warn. Drops the temporary hideAdhoc option.
@knudtty
knudtty requested a review from a team as a code owner November 13, 2026 21:36
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Nov 16, 2026 3:55pm UTC
hyperdx-storybook Ready Ready Preview Nov 16, 2026 3:55pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6a8bb20

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@hyperdx/api Minor
@hyperdx/app Minor
@hyperdx/otel-collector Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@knudtty
knudtty added this pull request to stack #3661 November 13, 2026 21:37
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

1 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 1 minor

None could be anchored to changed lines; they are listed below.

Findings outside the changed lines

1 minor
  • 🔵 packages/api/src/mcp/tools/dashboards/saveDashboard.ts:344 — With PromQL off, saving a dashboard warns that saved conditions for a hidden PromQL ad hoc filter will be ignored, which is wrong → effectiveFilters is the request's filters. Those never include hidden PromQL ad hoc filters, which are added back later as hiddenFilters. But convertToExternalDashboard still returns their adhoc entries in savedFilterValues. So when an agent re-sends what clickstack_get_dashboard gave it, getSavedFilterValueWarnings warns that no ADHOC filter matches and tells the agent to remove the entry. If it does, it deletes saved conditions that do apply. Fix: compute the hidden filters before building the warnings and pass [...filters, ...hiddenFilters]. patchDashboard.ts:281 already does this by passing existingDashboard.filters. Extend the 'keeps hidden PromQL ad hoc filters' test in promqlTiles.int.test.ts to send a saved adhoc value for the hidden filter and assert there are no warnings.

Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 108 in total (1.18%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

🔴 Tier 4 — Critical

Touches authentication, tenancy data models, the public API or shipped database config — or substantially changes the query rendering engine, background tasks, the OTel pipeline, image build, or release CI.

Why this tier:

  • Critical-path files (1) — tenancy, public API, or shipped database config:
    • packages/api/src/routers/external-api/v2/utils/dashboards.ts

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats
  • Production files changed: 13
  • Production lines changed: 297 (+ 273 in test files, excluded from tier calculation)
  • Critical-path lines changed: 29
  • Branch: aaron/adhoc-mcp
  • Author: knudtty

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 467 passed • 1 skipped • 1072s

Status Count
✅ Passed 467
❌ Failed 0
⚠️ Flaky 1
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found in the reviewer results and verification available at synthesis time.

This change brings the MCP dashboard tools to parity with the REST v2 API for ADHOC filters and fixes a real data-loss bug (a clickstack_save_dashboard update that sent filters previously deleted existing ad hoc filters). Independent verification confirmed three of the highest-risk areas are sound:

  • getSavedFilterValueWarnings name matching is correct. The adhocSourceTypeByName map is keyed on getFilterVariableName(filter) (which trims / derives the name) and looked up with value.name.trim(), so both sides normalize consistently — no false "matches no filter" warnings from whitespace or a derived default name. (validation.ts:270, common-utils/filters.ts:1263)
  • PromQL where-rejection and all REST superRefines run on the MCP path. createDashboard/updateDashboard re-parse through createDashboardBodySchema / updateDashboardBodySchema, so validateDashboardFilterFieldGating (which rejects where/whereLanguage on a promql ad hoc filter) is enforced for MCP exactly as for REST — the MCP input schema is only the tool's declared shape, not the validation boundary. (saveDashboard.ts:179, common-utils/dashboardValidation.ts:245)
  • Tenant scoping is preserved. Every read (getDashboard, getDashboardTile, queryTile, queryTiles) keeps Dashboard.findOne({ _id, team: teamId }), and save/update/patch keep team: teamId in their query filters. The patchDashboard response now returns updatedDashboard.savedFilterValues ?? [] directly, but reads from the just-written, team-scoped document, so no cross-tenant data becomes reachable.

🟡 P2 -- recommended

  • packages/api/src/mcp/tools/dashboards/validation.ts:289 -- The new adhoc write path (where/condition value now round-tripping through MCP) has no test asserting the shared query renderer safely handles adversarial where/value content, and the free-form where string remains unbounded (matching the pre-existing REST/QUERY_EXPRESSION surface rather than tightening it).
    • Fix: Add a test exercising adhoc conditions and where with SQL metacharacters through save → query to confirm they are parameterized/escaped at execution, and decide whether where should carry a max-length bound like the condition fields.
    • security

Reviewers (3 completed, 7 did not return before synthesis): project-standards, security, learnings-researcher completed. correctness, adversarial, api-contract, kieran-typescript, testing, and maintainability were dispatched but had not returned results at the time output was required, and agent-native did not return — their lenses (logic/edge-case bugs, adversarial data-mutation scenarios, contract/dangling-import checks, test-coverage of the data-loss fix) are therefore not reflected below. Treat this as a partial review.

Testing gaps:

  • No test confirming the core regression fix — that a save sending filters no longer deletes existing ad hoc filters — was verifiable from the completed reviewer set; confirm saveDashboard.int.test.ts asserts ad hoc filter persistence across such an update.
  • No negative test for cross-tenant isolation of adhoc filters/savedFilterValues (relies on existing team scoping).

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 6a8bb20f Deployed Nov 16, 2026 by vercel[bot]
Preview – hyperdx-storybook — 6a8bb20f Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-4 Critical — deep review + domain expert sign-off

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant